FOTOGRAMETRÍA — GUÍA COMPLETA (FASE 1 + FASE 2)
========================================================

Esta herramienta convierte fotos tomadas con el móvil en un modelo 3D,
en dos pasos:

  FASE 1 — Captura (página web, en el móvil)
      Se usa desde el navegador del móvil, en:
      https://teoriadeconstruccion.net/reality

  FASE 2 — Procesado (programa de escritorio, en el PC)
      Se descarga desde:
      https://teoriadeconstruccion.net/reality/descarga
      (la Fase 1 tiene un enlace directo a esta página)

No hace falta instalar nada en el móvil — la Fase 1 es una página web
normal. La Fase 2 sí es un programa que se instala en el PC.


¿EN QUÉ SISTEMAS FUNCIONA CADA FASE?
-----------------------------------------
FASE 1 (móvil): cualquier navegador moderno. Probado y pensado sobre
todo para Chrome en Android. En iPhone (Safari) funciona la captura de
fotos, pero algunas funciones no están disponibles porque Apple no las
expone a las páginas web (ver "Limitaciones en iPhone" más abajo).

FASE 2 (PC): **por ahora, SOLO WINDOWS.** No es una limitación
artificial ni algo "a medias" — la app depende de COLMAP (el motor de
reconstrucción 3D), y COLMAP solo publica binarios listos para usar de
Windows en su página oficial. Para Linux se instala por gestor de
paquetes (apt, conda) y para macOS no hay binario oficial en absoluto
— habría que compilarlo a mano en ambos casos. Dar soporte a Mac/Linux
es factible pero es un desarrollo aparte, no algo que funcione ya
"probando suerte" en esos sistemas. Si en algún momento se necesita,
hay que construirlo específicamente — avísame.


FLUJO DE TRABAJO COMPLETO
------------------------------
1. Desde el móvil, entra en teoriadeconstruccion.net/reality.
2. Activa la cámara y captura las fotos rodeando el objeto/espacio
   (ver la propia página para instrucciones de solape, bloqueo de
   enfoque, etc. — están integradas en la interfaz).
3. Exporta la captura: se descarga UN solo archivo .zip con las fotos
   y las posiciones juntas.
4. En el PC (Windows), descarga la Fase 2 desde el enlace de la propia
   página (teoriadeconstruccion.net/reality/descarga) — hay un botón
   directo tanto en la pantalla inicial como en el panel de capturas
   de la Fase 1.
5. Descomprime la Fase 2 en cualquier carpeta y abre "Iniciar.bat".
6. En la app: botón "Cargar zip..." y elige el .zip exportado del
   móvil. Se descomprime y se rellena todo solo.
7. Elige los formatos de salida que quieras y pulsa "Procesar".
8. Recoge el resultado en la carpeta de proyecto que hayas indicado.


1. REQUISITOS (FASE 2, WINDOWS)
------------------------------------
- Windows 10 u 11.
- Conexión a internet la primera vez (para instalar dependencias de
  Python y descargar COLMAP). Las siguientes veces no hace falta.
- Python instalado. Si no lo tienes, Iniciar.bat te avisa y te dice
  cómo conseguirlo.
- GPU NVIDIA: opcional. Con GPU, la reconstrucción es densa y con más
  detalle. Sin GPU, funciona igual pero con menos detalle (más lento
  también). Tarjetas NVIDIA muy antiguas (p.ej. Kepler, series 600/700)
  pueden no detectarse aunque existan, porque NVIDIA dejó de sacarles
  controladores — en ese caso la app usa correctamente el modo sin GPU.


2. INSTALACIÓN DE LA FASE 2 (SOLO LA PRIMERA VEZ)
------------------------------------------------------
1. Descarga el .zip desde teoriadeconstruccion.net/reality/descarga.
2. Descomprímelo en cualquier carpeta.
3. Haz doble clic en "Iniciar.bat". Si falta Python, te lo dirá con
   instrucciones. Las dependencias de Python se instalan solas.
4. La primera vez que le des a "Procesar", se descarga COLMAP
   automáticamente (200-400 MB, necesita internet en ese momento).


3. CÓMO USAR LA FASE 2
---------------------------
1. "Captura del móvil": botón "Cargar zip..." y elige el .zip que
   exportaste desde la Fase 1. Se descomprime solo y rellena la
   carpeta de fotos y el archivo de posiciones automáticamente.
   (Si tienes una captura antigua ya descomprimida en carpeta suelta,
   usa "Elegir carpeta..." en su lugar.)
2. Botón "Analizar captura" (opcional pero recomendado): revisa al
   instante si hay puntos de tu recorrido donde es probable que la
   reconstrucción se rompa (saltos de tiempo + giros bruscos, o
   cambios de zoom entre fotos), antes de lanzar el proceso pesado.
3. "Carpeta de proyecto": dónde se guardará el resultado.
4. "Calidad": rápido/media/alta/muy_alta — más alto = más detalle,
   más tiempo. Empieza por "rapido" para comprobar que todo funciona.
5. Marca los formatos que quieras: .glb, .stl, .ply, .las.
6. Opcional: "Nube de vistas" (posiciones reales de cámara) y "Modelo
   COLMAP en texto" (para otras herramientas/visores externos).
7. "Orientar automáticamente" viene activada por defecto: pone el
   plano con más puntos (normalmente el suelo) en Z=0. Ver sección 7.
8. Dale a "Procesar" y espera. Puede tardar desde minutos hasta más
   de una hora según la cantidad de fotos y la calidad elegida.


4. QUÉ ARCHIVOS OBTIENES
-----------------------------
En la carpeta de proyecto, según lo que marcaras:
  - modelo.glb  → para visores 3D genéricos, web, la mayoría de usos.
  - modelo.stl  → para software CAD/impresión 3D (sin color).
  - modelo.ply  → formato universal, con color, editable en Blender/
                  MeshLab/CloudCompare.
  - nube_puntos.las → la nube de puntos cruda con color, formato
                  estándar de topografía/escaneo 3D. Ábrela con
                  CloudCompare (gratis, cloudcompare.org).
  - camaras.glb → posiciones reales de cámara (si lo marcaste).
  - modelo_colmap_txt/ → modelo en texto plano (si lo marcaste).

Ningún archivo se sobrescribe: si repites el proceso, el siguiente
resultado se guarda como "modelo_2.glb", "modelo_3.glb", etc.


5. LIMITACIONES EN IPHONE (FASE 1)
----------------------------------------
Safari en iPhone no permite a las páginas web controlar el enfoque,
la exposición ni el zoom de la cámara — así que el botón de bloqueo de
enfoque/exposición no hace nada ahí (te lo avisa la propia página).
La captura de fotos en sí funciona con normalidad.


6. SOLUCIÓN DE PROBLEMAS (FASE 2)
---------------------------------------
"No se ha encontrado Python instalado en este PC"
  Instala Python desde https://www.python.org/downloads/ marcando
  "Add python.exe to PATH", y vuelve a abrir Iniciar.bat.

Error instalando dependencias mencionando "numpy", compilación, o
pidiendo un compilador de C
  Ejecuta una vez, desde una terminal en la carpeta del proyecto:
      python -m pip install -r requirements.txt --force-reinstall
  Si tu Python es extremadamente reciente (recién salido) y ni así
  funciona, instala Python 3.12 en paralelo (no hace falta desinstalar
  el que ya tienes) — es la versión con mejor soporte confirmado en
  todo lo que usamos.

Error "CERTIFICATE_VERIFY_FAILED" al comprobar COLMAP
  Windows/Python no encuentra los certificados raíz de confianza. Ya
  se usa un arreglo automático (librería certifi) para esto. Si
  persiste, es probable que un antivirus o proxy de empresa esté
  interceptando las conexiones HTTPS — consulta con tu departamento
  de informática si es un PC de trabajo.

El resultado sale con agujeros, incompleto, o "no se pudo generar
una malla"
  Casi siempre es poco solape entre fotos consecutivas, o superficies
  sin textura (paredes lisas, suelos muy pulidos, espejos, cristales).
  Revisa el informe de "Analizar captura" para ver dónde es más
  probable que se rompiera el recorrido.

Sin GPU NVIDIA, el resultado es más pobre que con GPU
  Es una limitación real, no un fallo: la reconstrucción densa de
  COLMAP necesita CUDA sí o sí. Sin GPU, la nube de puntos es más
  dispersa y la malla resultante, menos detallada.


7. ORIENTACIÓN AUTOMÁTICA AL PLANO DOMINANTE
----------------------------------------------------
COLMAP no tiene ninguna referencia de "hacia dónde es arriba" — el modelo
puede salir orientado en cualquier ángulo. Con la casilla "Orientar
automáticamente" (activada por defecto), la app detecta el plano con
más puntos coplanarios (normalmente el suelo, a veces un techo o una
pared grande) y gira + traslada todo el modelo para que ese plano quede
exactamente en Z=0, con el resto del modelo por encima.

Verificado con más de 30 pruebas controladas (inclinaciones y
desplazamientos aleatorios distintos, y también invirtiendo el orden de
los puntos): el plano detectado siempre termina en Z=0 y el modelo nunca
sale "boca abajo", pase lo que pase con el signo que calcule el detector
de planos internamente.

Esta app YA NO reescala el modelo — sale con la escala arbitraria que
calcula COLMAP. Si necesitas metros reales, ajusta la escala tú mismo
después (por ejemplo en CloudCompare, con la herramienta de medir
distancias) usando alguna referencia conocida en la escena.


8. CÓMO FUNCIONA POR DENTRO (OPCIONAL)
-------------------------------------------
Con GPU: COLMAP hace todo el proceso (features, matching, sparse SfM,
MVS denso, mallado Poisson) y usamos directamente su malla.

Sin GPU: COLMAP solo puede hacer la parte dispersa (sin reconstrucción
densa, que requiere CUDA). Sobre esa nube más ligera, se calcula una
malla Poisson con Open3D — el mismo algoritmo que usa COLMAP
internamente, pero aplicado a menos puntos, así que el resultado es
más aproximado.

Si procesas el mismo proyecto dos veces con las mismas fotos y la
misma calidad, la app se salta el trabajo pesado de COLMAP y reutiliza
lo ya calculado — mucho más rápido. Si cambia algo, rehace todo desde
cero automáticamente.

Si tienes el archivo de posiciones (orientación del móvil) en la
captura, se usa automáticamente para generar una lista de "qué fotos
probablemente se solapan" y acelerar el emparejamiento — esto no
cambia la calidad final, solo la velocidad.

El código de regularización por planos (paredes/techo/suelo rectos y
separación de muebles) sigue existiendo en regularize.py, pero ya no
se llama por defecto: con nubes de puntos dispersas daba resultados
pobres y solo añadía tiempo de proceso.
